<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->

<title>can_change_color</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_000_560">&nbsp;</a>NAME</h4><blockquote>
can_change_color, color_content, has_colors, init_color, init_pair,
start_color, pair_content - colour manipulation functions
</blockquote><h4><a name = "tag_000_000_561">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="curses.h.html">curses.h</a>&gt;

bool can_change_color(void);
int color_content(short <i>color</i>, short *<i>red</i>, short *<i>green</i>, short *<i>blue</i>);
int COLOR_PAIR(int <i>n</i>);
bool has_colors(void);
int init_color(short <i>color</i>, short <i>red</i>, short <i>green</i>, short <i>blue</i>);
int init_pair(short <i>pair</i>, short <i>f</i>, short <i>b</i>);
int pair_content(short <i>pair</i>, short *<i>f</i>, short *<i>b</i>);
int PAIR_NUMBER(int <i>value</i>);
int start_color(void);
extern int COLOR_PAIRS;
extern int COLORS;
</code>
</pre>
</blockquote><h4><a name = "tag_000_000_562">&nbsp;</a>DESCRIPTION</h4><blockquote>
These functions manipulate colour on terminals that support colour.
<h5><a name = "tag_000_000_562_001">&nbsp;</a>Querying Capabilities</h5>
The
<i><a href="has_colors.html">has_colors()</a></i>
function indicates whether the terminal is a colour terminal.  The
<i>can_change_color()</i>
function indicates whether the terminal is a colour terminal on which colours
can be redefined.
<h5><a name = "tag_000_000_562_002">&nbsp;</a>Initialisation</h5>
The
<i><a href="start_color.html">start_color()</a></i>
function must be called in order to enable use of colours and before any
colour manipulation function is called.  The function initialises eight
basic colours (black, blue, green, cyan, red, magenta, yellow, and white)
that can be specified by the colour macros (such as COLOR_BLACK) defined in
<i><a href="curses.h.html">&lt;curses.h&gt;</a></i>.
(See
<xref href=colourmacros><a href="curses.h.html#tag_000_000_258_006">
Colour-related Macros
</a></xref>.)
The initial appearance of these eight colours is not specified.
<p>
The function also initialises two global external variables:
<ul>
<p>
<li>
COLORS defines the number of colours that the terminal supports.  (See
<b>Colour Identification</b>
below.)
If COLORS is 0, the terminal does not support redefinition of colours (and
<i>can_change_color()</i>
will return FALSE).
<p>
<li>
COLOR_PAIRS defines the maximum number of colour-pairs that the terminal
supports.  (See
<b>User-defined Colour Pairs</b>
below.)
<p>
</ul>
<p>
The
<i><a href="start_color.html">start_color()</a></i>
function also restores the colours on the terminal to terminal-specific
initial values.  The initial background colour is assumed to be black
for all terminals.
<h5><a name = "tag_000_000_562_003">&nbsp;</a>Colour Identification</h5>
The
<i><a href="init_color.html">init_color()</a></i>
function redefines colour number <i>color</i>, on terminals that support the
redefinition of colours, to have the red, green, and blue intensity components
specified by <i>red</i>, <i>green</i>, and <i>blue</i>, respectively.  Calling
<i><a href="init_color.html">init_color()</a></i>
also changes all occurrences of the specified colour on the screen
to the new definition.
<p>
The
<i><a href="color_content.html">color_content()</a></i>
function identifies the intensity components of colour number <i>color</i>.  It
stores the red, green, and blue intensity components of this colour in the
addresses pointed to by <i>red</i>, <i>green</i>, and <i>blue</i>, respectively.
<p>
For both functions, the
<i>color</i>
argument must be in the range from 0 to and including COLORS-1.
Valid intensity values range from 0 (no intensity component) up to and
including 1000 (maximum intensity in that component).
<h5><a name = "tag_000_000_562_004">&nbsp;</a>User-Defined Colour Pairs</h5>
Calling
<i>init_pair()</i>
defines or redefines colour-pair number <i>pair</i> to have foreground colour
<i>f</i> and background colour <i>b</i>.  Calling
<i>init_pair()</i>
changes any characters that were displayed in the colour pair's old definition
to the new definition and refreshes the screen.
<p>
After defining the colour pair, the macro COLOR_PAIR(<i>n</i>) returns the
value of colour pair <i>n</i>.  This value is the colour attribute as it would
be extracted from a
<b>chtype</b>.
Conversely, the macro PAIR_NUMBER(<i>value</i>) returns the colour pair number
associated with the colour attribute <i>value</i>.
<p>
The
<i><a href="pair_content.html">pair_content()</a></i>
function retrieves the component colours of a colour-pair number <i>pair</i>.
It stores the foreground and background colour numbers in the variables
pointed to by <i>f</i> and <i>b</i>, respectively.
<p>
With
<i>init_pair()</i>
and
<i><a href="pair_content.html">pair_content()</a></i>,
the value of <i>pair</i> must be in a range from 0 to and including
COLOR_PAIRS-1.
(There may be an implementation-specific upper limit on the valid value
of <i>pair</i>, but any such limit is at least 63.)
Valid values for <i>f</i> and <i>b</i> are the range from
0 to and including COLORS-1.
</blockquote><h4><a name = "tag_000_000_563">&nbsp;</a>RETURN VALUE</h4><blockquote>
The
<i><a href="has_colors.html">has_colors()</a></i>
function returns TRUE if the terminal can manipulate colors; otherwise, it
returns FALSE.
<p>
The
<i>can_change_color()</i>
function returns TRUE if the terminal supports colors and can change their
definitions; otherwise, it returns FALSE.
<p>
Upon successful completion, the other functions return OK; otherwise, they
return ERR.
</blockquote><h4><a name = "tag_000_000_564">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_000_565">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
To use these functions,
<i><a href="start_color.html">start_color()</a></i>
must be called, usually right after
<i><a href="initscr.html">initscr()</a></i>.
<p>
The
<i>can_change_color()</i>
and
<i><a href="has_colors.html">has_colors()</a></i>
functions facilitate writing terminal-independent programs.  For example, a
programmer can use them to decide whether to use colour or some other video
attribute.
<p>
On colour terminals, a typical value of COLORS is 8 and the macros such as
COLOR_BLACK return a value within the range from 0 to and including 7.
However, applications cannot rely on this to be true.
</blockquote><h4><a name = "tag_000_000_566">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="attroff.html">attroff()</a></i>,
<i><a href="delscreen.html">delscreen()</a></i>,
<i><a href="curses.h.html">&lt;curses.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
